github.com/hyperion-hyn/go-ethereum@v2.4.0+incompatible/docs/Privacy/Constellation/How constellation works.md (about)

     1  ## How Constellation works
     2  
     3  Each Constellation node hosts some number of key pairs, and advertises
     4  a publicly accessible FQDN/port for other hosts to connect to.
     5  
     6  Nodes can be started with a reference to existing nodes on the network
     7  (with the `othernodes` configuration variable,) or without, in which
     8  case some other node must later be pointed to this node to achieve
     9  synchronization.
    10  
    11  When a node starts up, it will reach out to each node in `othernodes`,
    12  and learn about the public keys they host, as well as other nodes in
    13  the network. In short order, the node's public key directory will be
    14  the same as that of all other nodes, and you can start addressing
    15  messages to any of the known public keys.
    16  
    17  This is what happens when you use the `send` function of the Private
    18  API to send the bytestring `foo` to the public key
    19  `ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc=`:
    20  
    21    1. You send a POST API request to the Private API socket like:
    22       `{"payload": "foo", "from": "mypublickey", to: "ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="}`
    23  
    24    2. The local node generates using `/dev/urandom` (or similar):
    25         - A random Master Key (MK) and nonce
    26         - A random recipient nonce
    27  
    28    3. The local node encrypts the payload using NaCl `secretbox` using
    29       the random MK and nonce.
    30  
    31    4. The local node generates an MK container for each recipient
    32       public key; in this case, simply one container for `ROAZ...`,
    33       using NaCl `box` and the recipient nonce.
    34  
    35       NaCl `box` works by deriving a shared key based
    36       on your private key and the recipient's public key. This is known
    37       as elliptic curve key agreement.
    38  
    39       Note that the sender public key and recipient public key we
    40       specified above aren't enough to perform the
    41       encryption. Therefore, the node will check to see that it is
    42       actually hosting the private key that corresponds to the given
    43       public key before generating an MK container for each recipient
    44       based on SharedKey(yourprivatekey, recipientpublickey) and the
    45       recipient nonce.
    46  
    47       We now have:
    48  
    49         - An encrypted payload which is `foo` encrypted with the random
    50           MK and a random nonce. This is the same for all recipients.
    51  
    52         - A random recipient nonce that also is the same for all
    53           recipients.
    54  
    55         - For each recipient, the MK encrypted with the
    56           shared key of your private key and their public key. This
    57           MK container is unique per recipient, and is only transmitted to
    58           that recipient.
    59  
    60    5. For each recipient, the local node looks up the recipient host,
    61       and transmits to it:
    62  
    63         - The sender's (your) public key
    64  
    65         - The encrypted payload and nonce
    66  
    67         - The MK container for that recipient and the recipient nonce
    68  
    69    6. The recipient node returns a SHA3-512 hash digest of the
    70       encrypted payload, which represents its storage address.
    71  
    72       (Note that it is not possible for the sender to dictate the
    73       storage address. Every node generates it independently by hashing
    74       the encrypted payload.)
    75  
    76    7. The local node stores the payload locally, generating the same
    77       hash digest.
    78  
    79    8. The API call returns successfully once all nodes have confirmed
    80       receipt and storage of the payload, and returned a hash digest.
    81  
    82  Now, through some other mechanism, you'll inform the recipient that
    83  they have a payload waiting for them with the identifier `owqkrokwr`,
    84  and they will make a call to the `receive` method of their Private
    85  API:
    86  
    87    1. Make a call to the Private API socket `receive` method:
    88       `{"key": "qrqwrqwr"}`
    89  
    90    2. The local node will look in its storage for the key `qrqwrqwr`,
    91       and abort if it isn't found.
    92  
    93    3. When found, the node will use the information about the sender as
    94       well as its private key to derive SharedKey(senderpublickey,
    95       yourprivatekey) and decrypt the MK container using NaCl `box`
    96       with the recipient nonce.
    97  
    98    4. Using the decrypted MK, the local node will decrypt the encrypted
    99       payload using NaCl `secretbox` using the main nonce.
   100  
   101    5. The API call returns the decrypted data.
   102